Cream of the Crop 1

home *** CD-ROM | disk | FTP | other *** search

/ Cream of the Crop 1 / Cream of the Crop 1.iso / BBS / KGB_105C.ARJ / KGB.DOC < prev next >

Wrap

Text File | 1992-06-08 | 21KB | 453 lines

/*************************************************************/ /* K G B 1.05Γ Foul Language Remover for Hudson Base Systems */ /* Written by Alex Brodsky and Vulkan Technologies Inc. */ /* Copyright (c) 1992. All rights reserved. */ /*************************************************************/ Table of Contents Legal Stuff....................................Page 2 Purpose and General Overview...................Page 3 Operations.....................................Page 4 Command Line Parameters........................Page 5 Message Base Path.........................Page 5 Configuration File Parameters..................Page 5 Location..................................Page 5 Area Selectors............................Page 6 Breakers..................................Page 6 Bad Words.................................Page 7 Examples.......................................Page 8 Error Messages.................................Page 9 Bug Reports....................................Page 9 Contacting the Author, Famous Last Words.......Page 10 1.0 Legal Stuff PAGE 2 ----------- This program is freeware. You have the right to use this software as much as you want on as many machines as you want, whenever you want. You may distribute this software freely in its original form. You may modify your personal copy of KGB and release it to public use under the following conditions: 1. You must send the author the complete source of all the modifications you have made. 2. You must retain the original copyright notice and add your own. 3. You must clearly specify in your documentation the date(s) and type(s) of the modification(s) you have made to the program. 4. You must include a copy of this license with your release. 5. You MUST release it as freeware. You may NOT release it into the shareware or commercial market. This program comes with no warranty of any kind. It has been tested on several machines and seems to work with no problems. However, the author is not responsible for any damage caused by this software. You may not charge more than three Canadian dollars for transferal or copying services. This program may be included in any non-commercial package as long as the three dollar rule is not violated. Commercial users may use this program in their organization's internal operations, but may not release this software as part of their commercial packages. If a commercial organization wishes to sell this software as part of their package they must contact the author and purchase a license to do so. Any other software or companies mentioned in this document are trademarks of those respective companies and are used only to facilitate the explanation of this software. This concludes the legal part of this documentation. For a donation of ten dollars or more, you will receive the source code to this program. If you do use this program, I would really appreciate you sending me a quick netmail message saying so. Just to let me know that my efforts have not gone to total waste. <grin> 2.0 Purpose and General Overview PAGE 3 ---------------------------- 2.1 General Assumptions This document assumes that the user is familiar with the software and basic principles of Hudson Message Base operation. The user should have a basic knowledge of batch files and should be well versed in DOS. It is assumed that the user runs a bbs which uses the Hudson Message Base format. 2.2 System Requirements The requirements for this software are a Hudson Message and approximately 100K of memory. A configuration file for KGB must be present in the same directory that it is run or a full path he file must be entered as a command line parameter. For a discussion of the configuration file see page 5 of the documentation. DOS 2.0 is the minimum requirement however DOS 3.3+ is recommended. 2.2 What is KGB? KGB is a foul language remover for Hudson Style message bases. KGB looks for "bad words" which are listed in its configuration file and over writes them with a series of asterisks (*). Thus eliminating the word from the message and hopefully not drastically changing the content of said message. 2.3 General Operation KGB first looks for the configuration file, BADWORDS.CFG. After finding it, KGB loads the BADWORDS.CFG file. Once KGB loads the configuration file, it determines from the configuration file the location of the Hudson Message Base (HMB), which areas to scan, which breakers to use, and which words to scan for. For a further discussion of this see page 5. It then proceeds to look for a marker which it leaves in HMB after every scan, to determine from which point to start scanning. This makes KGB as efficient as possible. If it cannot find its marker, it will start from the beginning of the HMB and scan all of it. Once it has determined from which point to start scanning, it starts the memory intensive task of loading each message, scanning it for any of the black listed words and writing the masks back to disk once it has done so. Having finished all the scanning, KGB will then write a marker message so that it can determine from where to start scanning again the next day, and then proceeds to display the time it took for the entire operation. If at any time an error occurs, KGB will exit with an error level of 1, otherwise it will exit with an error level of 0. This is the general operations of KGB. 3.0 Operations PAGE 4 ---------- 3.1 Operating Procedures It is recommended that KGB is run once a night along with the other maintenance tasks which are preformed during the BBS's maintenance event. Just add KGB to the batch file which performs all the maintenance tasks. 3.2 Description of Operational Requirements As mentioned before, KGB must be able to find the BADWORDS.CFG configuration file. There are two ways that it can do so, the first way is to have the configuration file in the same directory that KGB is run. The second is for the user to specify the path to the BADWORDS.CFG as a command line parameter, this allows KGB to find the BADWORDS.CFG file no matter from where its run. For a further discussion of this see Page 5 of this manual. When KGB runs, it must be able to find all five files of the HMB, the five files that the HMB consists of, these files are MSGTXT.BBS, MSGHDR.BBS, MSGIDX.BBS, MSGTOIDX and MSGINFO.BBS. If it does not find these files, it will abort with an error. At the current time KGB only works with Hudson Message Base systems, however in later versions it will also be able to handle SQUISH and FTSC (*.MSG) format message bases as well. 3.3 Recommendations Using a disk cache to increase the speed of KGB is recommended and is theoretically quite safe. Since minimal writes are performed to the message base (unless the sysop has very profane users), there is almost no danger to the data since KGB is mostly a read intensive utility. Use as many wildcards as possible, for example, the word f*ck is found in several words like f*cker, motherf*cker, f*cking, etc. Use the word f*ck with wild cards instead of having KGB check for each of the above listed words, have it just check for f*ck with all its extenders thus saving time. For more on wild cards check page 7 of the manual. 3.4 Warning At this time KGB is not "share" friendly, if you are running in a multi-tasking environment make sure that when KGB is run, the files it requires are NOT being used by another process. 4.0 Command Line Parameters PAGE 5 ----------------------- KGB only takes one command parameter, this parameters is a path to the BADWORDS.CFG configuration file. This parameter is only necessary if you are running KGB from a different directory, or if the name of the configuration file is something other then BADWORDS.CFG. An example of this is KGB c:\bbs\cfg\badwords.cfg or KGB c:\bbs\othernam.cfg This allows you to run KGB with different configuration files and to run it from any directory and any drive. If this parameter is not used, KGB will look for the BADWORDS.CFG file in the directory that it is running, if it does not find it, it will abort with an error. 5.0 Configuration File ------------------ At the current time KGB takes 4 different verbs in the configuration file, however the next version will probably contain more. The four verbs are: 'location', 'areas', 'breaks', and 'list start'. At the current time it is recommended that the first 3 verbs be used in the configuration file before the fourth verb 'list start' The configuration file is a plain ascii file with each verb being on its own line, and followed by a CRLF pair, lower or upper case is of no consequence. Commenting the configuration file can be done by using the ; followed by the comment, a ; must precede a comment on every line. For an example of a configuration file take a look at the Examples section of this manual. All four verbs must be used in the configuration file and forgetting to put one will result in an abnormal termination of KGB. The descriptions of the verbs is as follows: 5.1 Location The 'location' verb tells KGB the directory in which to find the five files MSGHDR.BBS, MSGTXT.BBS, MSGIDX.BBS MSGTOIDX.BBS and MSGINFO.BBS. During the execution of KGB, it will display the path which is listed in the configuration file. The syntax for this verb is: location d:\path\to\directory e.g.: location c:\bbs\msgbase The five files would be located in the directory msgbase, putting a '\' after msgbase is unnecessary but will not affect the run-time operation of KGB. 5.0 Configuration File Continued PAGE 6 ---------------------------- 5.2 Areas The 'areas' verb tells KGB which areas of the HMB to scan. There are two different things that KGB gets from this verb and there are several ways of doing it. The two things the KGB learns from this verb are which areas to scan and in which area to place the marker message. This is indicated by a string of numbers separated by commas and/or the 'all' qualifier. The first number after the verb is the area number in which KGB will place the message marker. The numbers that follow either include or exclude the areas to be scanned depending on the 'all' qualifier. The all qualifier tells KGB whether to include or exclude message areas to scan. If the 'all' qualifier is used, then KGB will scan ALL the message bases except the ones following the 'all' qualifier. If the 'all' qualifier is not used then KGB will scan all the numbers listed. The area number in which to place the marker must come before the 'all' qualifier. if there is no number before the all qualifier, then KGB will place the marker in area 1. The syntax for this verb is as follows. areas (numbers delineated by commas.) e.g. areas 2,all,24,26 this tells KGB to place its marker in board 2, and scan all message bases except 24 and 26. See the examples section for further examples of this Verb. 5.3 Breakers The 'breakers' verb tells KGB which breakers to use when scanning. Breakers are characters which delineate text. The most common breaker is the <space> others are periods, asterisks, and commas. KGB takes a user defined list of breakers which it adds to the beginning and end of each word for which it scans in the text. The space must be included between 2 other breakers because it would otherwise get truncated by KGB. A ; may not be used as a breaker since it also denotes a comment in the configuration file. The syntax for this verb is: breakers (breakers to be used) e.g. breakers !@#$%^&*()_+-= |{}[]":'/,<> 5.0 Configuration File Continued PAGE 7 ---------------------------- 5.4 List start It is recommended that this verb be used last in the configuration file because after it follows the list of black listed words. The function of this verb is to signal to KGB that the list of unwanted words begins on the next line. There are no qualifiers following this verb. The words following this verb are all the words that KGB scans for there are 4 different ways that they can be scanned for, and the four different ways all deal with wild cards. The normal way that the word is entered is without wild cards, however some words are never used to compose non dirty words like f*ck and sh*t. These words are considered "dirty" no matter what context they are in, hence fourth, these words can be wild carded. The difference between regular words and wild card words is in the way KGB scan for them. With regular words, KGB attaches breakers to both front and back of the word, with wild card no breaker is attached to either and/or both ends of the word. Thus without breakers the word can be found in a lot more contexts then with breakers. The wildcard is represented by an asterisk (*). Finally only single words are allowed, two words on same line will get truncated to 1. The syntax therefore is: list start (list of bad words) e.g. list start badword1 badword2* *badword3 *badword4* As you can see from the example the first word will have breakers attached to it when it is scanned, the second word will only have breakers attached before it, in word 3 the breakers will only be attached afterwards and in word 4 no breakers will be used. Using wild cards to scan is a lot faster then with breakers, however with words like 'ass' which makes up words like 'assume' and 'association' breakers are necessary. See the examples section of this manual for more clarity. 6.0 Examples PAGE 8 -------- 6.1 Command parameters for KGB: KGB c:\bbs\badwords.cfg KGB will look in c:\bbs for the configuration file called BADWORDS.CFG KGB KGB will look in the current directory for the file BADWORDS.CFG KGB d:\bbs\cfg\xxx.cfg KGB will look for the configuration file named XXX.CFG in the d:\bbs\cfg directory. 6.2 Configuration File example ;This is a configuration file for KGB ;The Message base is to be found in the c:\bbs\msgbase ;directory location c:\bbs\msgbase ;KGB will scan ALL the areas except 200, 24, 26 and 13. It ;will place the marker message in area 7. areas 7,all,26,24,200,13 ;The breakers used in the scanning process will be... ;use of the semicolon ';' is not allowed breakers !@#$%^ &*()_+-=\|{}][:"'/?>< ;The bad words will now be listed, some will use wildcards list start badword1 ;no wild card use badword2* ;wild card at end of word, no end breaker used *badword3 ;wild card at start, no start breaker used *badword4* ;wild card used at both ends no breakers used! This a typical configuration file, except that the badword? are replaced by actual "dirty" words which I am trying to avoid while writing these docs. 7.0 Error Messages Glossary PAGE 9 ----------------------- 7.1 Memory allocation Error: This error is fatal, that is KGB will immediately terminate its operations. This is usually caused by insufficient memory to run KGB which requires about 100k of memory. To correct this problem simply flush some of your TSRs from memory to allow KGB more memory. 7.2 File Open Error: If KGB does not find the files it requires it will abort. The solution to this problem is to make sure that all required file are available. Make sure that all the paths in BADWORDS.CFG and command line parameters are correct. Finally, this version of KGB is NOT share friendly, and therefore running it in a "share" environment will cause it to terminate if it accesses a file, which has been already accessed. 7.3 File Read Error: If KGB encounters a problems during the reading of a file, e.g. a bad disk sector, it will return a read error, just like in the case of the File Open Error, KGB will either exit with a fatal termination error. 7.4 File Seek Error: Same as File Read Error except the error occurred on a file seek action instead of a file read action, same criteria apply. 7.5 File Write Error: Same as File Read Error except the error occurred on a file write action instead of a file read action, same criteria apply. 8.0 Bug reports, If you find any bugs, please report them to me as soon as possible. I have done my best to ensure that KGB is as bug- free as possible. However no program is perfect, so if you do find any bugs please let me know. If you are getting an abnormal termination (which you shouldn't), and you don't know why, send me a netmail with the termination code and I'll try to help you. 9.0 Contacting the Author And Famous Last Words PAGE 10 ------------------------------------------- 9.1 Contacting me You may contact me at the following BBSes. DPSHQ (416) 374 6188 (1:247/205) Front End Mailer only (416) 374 3215 BBS only DOB (416) 937 1907 (1:247/101) You may send me netmail at 1:247/191 You may also write to me at: 38 Elma St. #11, St. Catharines, ON, Canada, L2N 6Z3. 9.2 Author's Note I have written KGB at the request of a friend who needed a foul language remover for his BBS. I hope that it does not get abused and that most sysops will exempt the private area from KGB's scan. An appropriate tone must be maintained in the public echoes, but in private conversation people should be allowed to express themselves without having their conversation censored. Although KGB is only capable of working on Hudson Base messages it will in the future release be capable of working on SQUISH and FTSC (*.MSG) message bases as well will be more configurable. 9.3 Famous Last Words ----------------- I would like to thank Paul Doerwald (1:247/201) for providing me some necessary information. I would also like to thank Russ Pettifer (1:247/116) who originally asked me to write this program. I would like to dedicate this program to the Dead Programmers' Society (DPS), and to all programmers out there who have been forced to write documentation. It is however necessary to note that as I wrote this documentation, I was able to correct some of KGB's original design flaws making it easier to use. Moral: Even if it doesn't help the user, it helped me. And finally: You know when you are having a bad day when your LINT begins to insult you more then you insult the computer.